{{indexmenu_n>1}}

===== Help Information ======
This page is available from within the plugin via the **Help** Menu by selecting **Information**

Weather Routing Plugin for OpenCPN by Sean Depagnier

===Introduction===

The Weather Routing Plugin is designed to compute iteratively positions the boat could possibly make at a certain time. By merging the results of many calculations, it is possible to form a map determining routes to any given location within the map.

===Quick Start===

First, load the grib file used for routing using the grib plugin. Next, open the Weather Routing plugin from the main toolbar and right click the map and Select "Weather Route Position" at the starting location. Repeat this step for the destination. Now, in the Weather Routing window from the Configuration menu (next to File) Select "New". From here you must configure your vessel correctly in the boat dialog; add a polar to specify how the boat sails. When ready, select "Compute" from the Configuration menu to compute the weather route.

===Background===

Integration with the grib plugin allows for knowledge of weather conditions. The climatology plugin can also provide a source of data for longer voyages, but be warned that using the climatology data, especially in variable wind areas is unlikely to give realistic results. Using climatology for currents is more useful and can be used with grib wind data when grib current data is not available.

For example, in the case where data is valid from both sources, grib will always be choosen. If current data is available from climatology, and only wind from grib, then the grib wind is used with the climatology current.

The grib time selected on the timeline at the time the computation is started can be syncronized. From there, the grib timeline data is accessed as the computation proceeds. Once a computation is completed, the course and position of the boat as it sails along the computed route can be viewed during grib playback.

Wind data is required; if no Current or Swell data is available, they are assumed to be zero.

=====Configuration =====

==== Basic Tab ====

===Start===
  * Position: Select start position from drop down menu 
===End===
  * Position: Select end position from drop down menu 
===Time===
  * Date: Select Date
  * Grib Time: Sets date & time to Grib_pi active file date & time. Adds checkmark.
  * Current Time: Sets date & time to current date and time. Removes checkmark.
===Time Step===
  * Time to sail before considering a course or sail change. This is the difference in time between the isochrons on the map. Small time-steps are needed to navigate through narrow channels and give a more accurate result. Generally the route's computed time becomes faster with smaller time steps as it can find a more optimal route with more variation, however it will take longer to calculate (generally four times longer for half the time step).
  * Hours, Minutes, Seconds
===Boat===
==Path to Boat.xml==
  * Click on the "..." to set the path or change the Boat.xml file.
  * Windows Example: C:\ProgramData\opencpn\plugins\weather_routing\boats\NorthStar.XML
==Edit Boat.xml==  
  * Edit //Boat.xml// opens up a menu intense portion of the Routing Configuration:
  * **Plot Tab** specifies the parameters for the plot displayed.
    * **Polar** Typical polar diagram showing boat speeds at a given wind speed.
    * **Speed** Plot boat speed across all wind speeds at a given wind angle.
    * The tracking displays give data based on the mouse position over the plot.
  * **Crossover Tab** Shows the relationship of the polars and which one is used for each condition.
  * ** Stats** Shows optimal Target Boat Speeds and Angles at downwind/upwind port/starboard tacks at various wind speeds.
  * Bottom Drop Down Menus
    * **Polar** diagram and **Speed** orthogonal diagram
    * **True Wind Direction / True Wind Speed** Selection of combinations of Wind direction &  speed to use.  
  * **Add Polar**  Files from the Boat.xml file.
  * **Remove Polar** Files from the Boat.xml file. 
  * **Open Boat**  Open an existing boat file.
  * **Save Boat**  Save current boat file.
  * **Save As Boat** Save current boat file to a new name.
  * Multiple polar files can be added to the Boat.xml for: 
    * See the example polar files.
    * Wind Ranges (light, medium, heavy) and corresponding Sail Sets.
    * Sea State (flat, chop, rough)
    * Bottom Condition
    * Power Polar for light winds
    * The best polar file will be automatically selected for the routing when the route is being "Computed".
  * **Edit** //Polar File (.csv .txt .pol)// opens up another window which permits editing the polar file. 
    * **Grid Tab** Edit values in individual cells. Note use of:
      * blank = Interpolate from nearby values, if at least one set of values of tws/twd are entered in the column/row.
      * 0 = Not recognized by the program, will remove these it edited. Sometimes a polar will contain 0's. They should be removed.
      * 0.0 = Specifies invalid (cannot be used). Boat won't move and can't go there.
      * **Cancel** and **Save** 
    * **Dimensions Tab** Use to add or remove wind angle/speed columns/rows
      * Set the values in the the  first column (twa) and first row (tws).
      * **Cancel** and **Save**
    * **Generate Tab** Generate a boat polar from Boat Characteristics (VPP) or from actual Measurements of Wind Dir/Speed.
      * **Cancel** and **Save** 
      * This feature is not fully implemented. 
=== Constraints ===
==Max Diverted Course==
  * Maximum course error to continue toward destination. Not all possible courses will be considered and therefore the most optimal route may not be found. This usually (but not in all cases) is obvious when the optimal route is sometimes near the edge of the graph. Using a reasonable value can greatly speeds the rate of computation.
==Max True Wind==
  * Knots. Do not navigate in areas with more true wind than this value.
==Max Apparent Wind==
  * Knots. Do not navigate in areas with more apparent wind than this value. This should be set to a high value (ie: 100) if not used to avoid extra calculations.
==Max Swell Meters==
  * Do not attempt to navigate in areas with more wave average height than this value.
=== Options ===
==Detect Land==
  * Use GSHHS coastline data to avoid sailing through land. This check is quite slow and should be optimized in the future. It is recommended to upgrade to the high resolution background map available here.
==Detect Boundary==
  * If OcpnDraw Plugin is enabled and an exclusion Boundary exists, avoid it.
==Currents==
  * Use current data if available.
==Optimize Tacking==
  * Boat may sail on all courses 0-360, even directly upwind and it is assumed that the captain performs tacking at the optimal angles to closely approximate the generated weather route for upwind and downwind. Tacks will not be visible in the generated route. This may allow navigation in tighter areas, or otherwise better results without decreasing the time step.

===Data Source===
==Grib== 
   * **Enable** Using current grib from grib plugin. Must be a valid grib file. 
   * Suggest that it be set at the projected start time so "Grib Time" can be used.
==Climatology==
  * **Disable** Do not allow climatology to be used.
  * **Currents Only** Use climatology for currents, but never wind.
  * **Cumulative Map** Pretend the wind comes from all of the directions in the wind atlas for the percentage of time based on the atlas. For this mode to work optimally, you should sail at all angles from 0 to 360, and enable "optimize tacking". This will allow the program to assume you will tack as needed in intervals shorter than the isochrons to take advantage of wind shifts.
  * **Cumulative** Calms Like //Cumulative Map//, except the boat also drifts without sailing during calms.
  * **Most Likely** Use the interpolated most likely wind data from the wind atlas, with the most likely wind speed.
  * **Average** Use wind vector average for wind direction, and wind magnitude average for wind speed. This is the fastest to compute, but not very realistic (it may be close in prevailing conditions).
==Last Valid==
  * Wind Data if Deficient Continue to navigate on last valid wind data even if there is no more valid wind data in the area/time. Currents will be assumed to be zero if data is deficient. Cases with deficient data include navigating outside the space or time of the grib file without climatology data, or into an area also not covered by climatology.

==== Advanced Tab ====
=== Constraints===
==Max Latitude==
  * Do not navigate above (or below in the southern hemisphere) this latitude.
==Wind VS Current==
  * When wind opposes current rough seas can be produced. This constraint takes the dot product of the current and wind vectors, and if the result exceeds this value, navigation in this area is avoided. For example, a value of 60 would avoid 30 knots of wind opposing a 2 knot current as well as 20 knots of wind opposing a 3 knot current. Higher values allow for rougher conditions; the special value 0 (default) allows any conditions.
==Max Course Angle==
  * Like Max Diverted Course, except the search range is based from the starting position to the destination. Normally should be set to 180.
==Max Search Angle==
  * This specifies how much the boat course can change between propagation. A value of 180 gives the maximum flexibility of boat movement, but increases the computation time. A minimum of 90 is usually needed for tacking, a value of 120 is recommended with strong currents. Smaller values (60 or less) can give very fast results, but should be used with care, as if the other settings are not appropriate, an inaccurate graph will result. For example, if tacking is needed at any time, then in this case, all courses (0-360) must be specified as degree steps and "optimize tacking" should be enabled.
==Avoid Cyclone Tracks==
  * Uses climatology cyclone tracks to avoid routings which cross historic cyclones. The settings in the climatology configuration for windspeed, pressure elnino etc are used, so only visible tracks are considered.
=== Options ===
==Inverted Regions==
  * This is relatively rare, but in some cases it may be possible to reach a location from two different routes (imagine either side of an island) which is further away from the destination before the destination can be reached. At this point, the algorithm must invert and work inwards on this inverted region (rather than outwards) to possibly reach the destination. This case can occur when routing around islands, or occasionally when routing near a high pressure system. Normally this should be disabled, and extra computations are avoided. NOTE: this mode has bugs
==Anchoring==
  * In some cases, it may be preferable to anchor (assuming it isn't too deep) rather than continue to navigate if there is a contrary current which is swifter than the boat can travel. This allows the route to reach the destination sooner by sitting in place until the current abades.
==Integrator== 
  * **Newton's method** is default and fastest, but doesn't take into account changes in wind/current along each step. 
  * **Rutta Kunge** (4th order) is much more accurate taking 4 samples, but a lot slower. 
  * Generally Newton's method with a smaller time step is recommended for more accuracy.
==Wind Strength Percentage==
  * Multiply wind strength from data source by this percentage to allow computation of possible "what if" scenarios of greater or lesser wind strength.
==Tacking time==
  * Tacking Time Penalty for course change from one tack to the other in seconds. This is normally irrelevant for ocean passages, but could be useful for routes in tight quarters Setting to 0 avoids extra calculations.
==Safety Margin from Land==
  * Safety margin number of nautical miles from land. (Sometimes this interferes with close shore Start and End positions).  
==Courses Relative to True Wind==
  * A list of courses to attempt sailing. Excluding certain values can force the route to explicity show tacks/jibes. Another option is to remove all upwind values to find a course which is always running off the wind (even if it is much longer.) Good results typically have a course every 3-5 degrees; more steps takes longer computation time.
==Reset all Advanced Parameters==
  * Reset the advanced parameters to the default [[opencpn:opencpn_user_manual:plugins:weather:weather_routing:settings|Configuration Defaults]]

=====Failures=====

If the route fails to complete there are various reasons why displayed in the status column of that configuration.

  *  Grib data not available at the needed time step. This is different from being outside of the grib area.
  *  Climatology Can only occur if trying to avoid climatology cyclone data and the data isn't available.
  *  Polar Occurs when there is no polar defined for the conditions.
  *  No Data Occurs when navigating in an area where there exists no wind data.

It is also possible to fail with none of the above specified. In this case it is likely due to the configuration settings being too restrictive.

It is possible to be restricted by constraints in one area, not have data in another area and have undefined polar data elsewhere, and changing any of the three allows for a successful route. For this reason the cause of failure may be unclear.
Batch Mode

Once a weather route is successfully computed, it is possible to determine the best time to leave. To do this, many configurations must be generated each with a different start time. Starting by selecting a single configuration with the earliest starting time. From the configuration menu, select batch (ctrl+b) From here, enter the number of days/hours to generate spans. Using decimal values for hours is allowed (ie: 0.5 for half-hour) Once generate is selected, many configurations should appear. Now, "Compute All (ctrl+a)" can be selected from the configurations menu. A total progress bar can be seen under the configurations. Finally a report describing the routes is available from the View menu.
Boat

The boat dialog displays the polar plot of the boat's speed vs true wind direction as well as showing other details. An xml file specifies the boat parameters and each sail plan. Two file types of polars are supported; CSV (same as qtVlm) and xml parameters which describe how to compute the polar.
